home *** CD-ROM | disk | FTP | other *** search
/ CU Amiga Super CD-ROM 27 / CU Amiga Magazine's Super CD-ROM 27 (1998)(EMAP Images)(GB)[!][issue 1998-10].iso / CUCD / Programming / Mesa / quantizers / quantizer.doc
Encoding:
Text File  |  1998-08-02  |  6.0 KB  |  188 lines
  1. TABLE OF CONTENTS
  2.  
  3. quantizer/--background--
  4. quantizer/InitQuantizer
  5. quantizer/DeleteQuantizer
  6. quantizer/ResizeQuantizer
  7. quantizer/Quantize
  8.  
  9. quantizer/--background--                             quantizer/--background--
  10.  
  11.    NAME
  12.         quantizer - Quantizer plugin library for AmigaMesaRTL.
  13.  
  14.    PURPOSE
  15.         This document describes the quantizer interface that AmigaMesaRTL
  16.         expects.
  17.  
  18.         A quantizer has two purposes: to reduce the number of colours to the
  19.         display depth, and to output the quantized buffer to the window. A
  20.         quantizer should support both RGBA and Index mode buffers.
  21.  
  22.         When a new context is created, the quantizer library requested by the
  23.         user is opened using OpenLibrary(). If opened successfully,
  24.         InitQuantizer() is called. Do whatever setup is needed here. If all
  25.         goes well, ResizeQuantizer() will be the next thing to be called. If
  26.         something goes wrong, or the user wants to destroy the context,
  27.         DeleteQuantizer() will be called. You should be prepared to receive a
  28.         DeleteQuantizer() call at any time after InitQuantizer() has been
  29.         called.
  30.  
  31.         All the hard work is done by Quantize(). Here you should do whatever
  32.         is necesary to draw the given buffer to the window. To accomodate
  33.         multiple windows on the same screen on AGA, the user can specify a
  34.         palette index range to which the quantizer should restrict the
  35.         output if in RGBA mode.
  36.  
  37.         See the dl1 quantizer source for an example implementation.
  38.  
  39. quantizer/InitQuantizer                               quantizer/InitQuantizer
  40.  
  41.    NAME
  42.         InitQuantizer - Initialize the quantizer.
  43.  
  44.    SYNOPSIS
  45.         result = InitQuantizer(window, mode, numcolours, firstcolour)
  46.         D0                     A0      D0    D1          D2
  47.  
  48.         int InitQuantizer(struct Window *, ULONG , ULONG , ULONG);
  49.  
  50.    FUNCTION
  51.         The quantizer is initialized. This will be called only once for a
  52.         context. No, you don't get access to the context itself.
  53.  
  54.         The given window is the window created for the context, and where the
  55.         user is expecing the quantizer to draw the output to. You probably
  56.         want to store away the pointer somewhere, as the quantizer is not
  57.         going to get again.
  58.  
  59.         The mode tells you what format the buffer is going to be in.
  60.         Currently only AMRTL_RGBAMode and AMRTL_IndexMode are supported.
  61.  
  62.         The colour range is the palette index range which the user expects
  63.         the buffer to be quantized to. The palette index range is
  64.              [firstcolour , ... , firstcolour+numcolours-1]
  65.         and can be assumed to be a valid range for the window. So for
  66.         example, if numcolours==128 and firstcolour==16, the quantizer should
  67.         touch only palette entries 16, 17, ..., 127.
  68.  
  69.         If the quantizer is for a truecolour display, it doesn't make much
  70.         sense to take any notice of the colour range values of course.
  71.  
  72.         If the quantizer doesn't support a given mode, failure should be
  73.         signalled by returning 0.
  74.  
  75.    INPUTS
  76.         window - Window associated with the quantizer.
  77.         mode - Buffer format, either AMRTL_RGBAMode or AMRTL_IndexMode.
  78.         numcolours - Number of colours to quantize to.
  79.         firstcolour - Palette index of the start of palette range.
  80.  
  81.    RESULTS
  82.         result - 0 if the quantizer failed to initialize, non-zero otherwise.
  83.  
  84.    BUGS
  85.         None
  86.  
  87.    SEE ALSO
  88.         DeleteQuantizer()
  89.  
  90. quantizer/DeleteQuantizer                           quantizer/DeleteQuantizer
  91.  
  92.    NAME
  93.         DeleteQuantizer - Delete the quantizer.
  94.  
  95.    SYNOPSIS
  96.         DeleteQuantizer()
  97.  
  98.         void DeleteQuantizer(void);
  99.  
  100.    FUNCTION
  101.         The quantizer is deleted. This can be called anytime after the
  102.         InitQuantizer() function has been called. This includes the case when
  103.         the quantizer failed to initialize.
  104.  
  105.         This function will be called before the quantizer library is closed.
  106.  
  107.    INPUTS
  108.         None.
  109.  
  110.    RESULTS
  111.         None.
  112.  
  113.    BUGS
  114.         None
  115.  
  116.    SEE ALSO
  117.  
  118.  
  119. quantizer/ResizeQuantizer                           quantizer/ResizeQuantizer
  120.  
  121.    NAME
  122.         ResizeQuantizer - Resize the quantizer.
  123.  
  124.    SYNOPSIS
  125.         result = ResizeQuantizer(width, height)
  126.         D0                       D0     D1
  127.  
  128.         int ResizeQuantizer(int, int);
  129.  
  130.    FUNCTION
  131.         When the window size is set to a new value, the buffer may resized as
  132.         well. This function is called when the buffer changes size. The given
  133.         size may or may not correspond with the window size.
  134.  
  135.         The width is guaranteed to be a multiple of 16.
  136.  
  137.         ResizeQuantizer() will be called at least once after InitQuantizer()
  138.         is called and before Quantize() is called, unless the quantizer is
  139.         deleted in the meantime.
  140.  
  141.    INPUTS
  142.         width - Width of buffer, a multiple of 16.
  143.         height - Height of buffer.
  144.  
  145.    RESULTS
  146.         result - 0 if the quantizer failed to resize, non-zero otherwise.
  147.  
  148.    BUGS
  149.         None
  150.  
  151.    SEE ALSO
  152.  
  153.  
  154. quantizer/Quantize                                         quantizer/Quantize
  155.  
  156.    NAME
  157.         Quantize - Quantize and output a buffer.
  158.  
  159.    SYNOPSIS
  160.         result = Quantize(buffer)
  161.         D0                A0
  162.  
  163.         int Quantize(APTR);
  164.  
  165.    FUNCTION
  166.         Using the parameters passed to InitQuantizer() and ResizeQuantizer(),
  167.         the given buffer is quantized and drawn.
  168.  
  169.         If the mode is AMRTL_RGBAMode, the buffer contains height*width*4
  170.         bytes in RGBA order. If the mode is AMRTL_IndexMode, the buffer
  171.         contains height*width bytes where each byte represents an index. The
  172.         indices will have been corrected to start at firstcolour.
  173.  
  174.         The buffer should not be modified in any way by Quantize(), as the
  175.         user may want to read pixels from it, or process it further.
  176.  
  177.    INPUTS
  178.         buffer - Buffer to quantize.
  179.  
  180.    RESULTS
  181.         result - 0 if the quantizer failed to quantize, non-zero otherwise.
  182.  
  183.    BUGS
  184.         None
  185.  
  186.    SEE ALSO
  187.         InitQuantizer(), ResizeQuantizer()
  188.